Shareware Grab Bag/Shareware Grab Bag.iso/007/partner.arc/PARTNER.DOC

Text File | 1985-05-11 | 26KB | 582 lines

           ________________________________


             P A R T N E R    Version 1.1

           ________________________________



                   C o m p u C a m

                   45 Parklea Drive
                   Toronto, Ontario
                        Canada
                       M4G 2J7
                    [phone]

              (evenings after 7:00 EDT)


PARTNER is distributed as a freeware program.  That is, you may use it,
copy it and distribute it.  You may not, however, sell it.  PARTNER, and
the original ideas behind it, remain the property of Jim Camelford and
CompuCam.  If you have found the program useful, we would appreciate a
donation of $15.00 (CDN).

PARTNER's source code and documentation (in machine-readable form) are
available at a nominal cost to cover handling charges.  If you are
interested, please contact the author at the above address.  PARTNER
is written in TURBO (tm) Pascal.  You may wish to obtain the source code
if you want to see how it's done, modify the program's operation to add
features of your own or generate different versions that use less memory.

Of course, we would be delighted to hear your comments and will attempt to
fix any reported bugs in either the documentation or the program.  English
isn't exactly free of glitches either!  Write us!

PARTNER is not, however, warranted in any way nor are any claims made as to
the suitability of the program for your application.


          PARTNER Copyright (c) 1985 James R. Camelford
   ________________________________________________________________

PARTNER - What is It ?
======================
PARTNER is a useful utility program that resides permanently in your
system's memory yet is available at any time with the touch of a key.
It provides a set of useful diskette and directory maintenance facilities
that can enhance most programs running on your PC.

For example, it provides:

      o  multiple-window access to the directories on your diskettes or
         hard disk;

      o  an ability to remove, copy and rename files;

      o  a technique to move files from one sub-directory to another on
         the same volume without copying and removing;

      o  a capability for displaying (ie: typing) text files on your screen;

      o  reports of space usage for individual files and for the volume as
         a whole;

What it Doesn't Do
==================
Because PARTNER uses colour extensively, it requires a colour/graphics
adapter.  In its conventional form, it requires about 52kb of permanent
memory.  PARTNER could easily be modified to sense which type of display
it's using and to use only monochrome.  It is not currently compatible
with 40-column or graphics display modes.  It's been tested on true IBM PC's,
PC's with hard disks, AT's and the Advanced Colour/Graphics adapter and
found to work well.

PARTNER works well with a variety of programs.  However, it is known to
be incompatible with some.  A list and technical description is provided
at the end of this document.

How you Start the Program
=========================
You invoke PARTNER from the DOS command prompt using the following command.
(The square brackets indicate optional parameters just like in the DOS
manual.)

         PARTNER [/load]  [/nnn]

          /load    causes PARTNER to be permanently retained in memory as
                   an extension to DOS.  If you do not use the /load
                   option, then PARTNER runs as a utility program and
                   exits normally when you are done.  When PARTNER is run
                   as a utility, it waits for 5 seconds to display its
                   logo before allowing you to enter a command).

          /nnn     the scancode of the keystroke you want to use to invoke
                   PARTNER once it is loaded, either from the DOS command
                   prompt or from within a running program.  By default,
                   PARTNER uses shift-F9 (that is: 92).  You can set the
                   signalling keystroke to any convenient key.

PARTNER - How to Use it
=======================
PARTNER is pretty simple to use!  (Of course that may be construed as
literary license on my part ... but the approach we will take for teaching
you how to use it is by taking you through a step-by-step sequence ...)

Bring PARTNER up as a utility program first.  That is, just run it from
the DOS command prompt using the command:

                        PARTNER

Do not specify any options.  PARTNER will display its logo, wait 5 seconds
and then offer you a small window in the upper left corner of your screen.
(Yes, you can change its shape and location but let's leave that until
later ...)

PARTNER prompts you for a Directory Name.  Enter a directory name using
the same syntax as you would for DOS' DIR command.  In this state,
PARTNER understands drive letters, wildcard constructs using  * and ?
and sub-directories  -- so use them if you like.  Alternatively, you can
simply strike the RETURN key (without typing anything) if you want a
display of all filenames on the default directory on the default drive.

PARTNER displays a list of filenames on the volume until either it fills
the window (ie: runs out of space) or runs out of filenames.  At this point,
it pauses and highlights the filename in the upper left corner of the
window.  You can "operate" on this file using the features described below.

Now the fun starts, since now all the options are available to you ... and
there are lots of them.  But first, look at the bottom line of the window.
This is know as the Help line.  It lists some of the functions now
available (eg: Remove, Rename, Change Directory ...).  Watch the help
line from time to time as it will contain additional, explanatory
information to assist you when entering a command.

The functions now available are briefly listed below; more detail follows
later:

      Enter     Specify a different wildcard sequence, drive,
                filename or sub-directory

      F2        Remove this file

      F4        Copy this file somewhere

      F6        Rename this file

      F8        Change the default sub-directory for this window
                to something else

      F10       Display additional information about this file
                (ie: creation timestamp, file size, file attributes etc).

      F9        Display (ie: type) this file on the screen now

      F1, F3    Shrink or grow the window's horizontal size

      F5, F7    Shrink or grow the window's vertical size

You can move about the window, selecting different files, using the normal
cursor movement keys.  That is:

      -> <-     Moves the "file pointer cursor" right or left

      ^ |       Moves up or down
      | v

      home      Moves to the upper left corner

      PgUp      Starts the display of filenames all over again
                from the first file in the directory (that is,
                it's a "start over" key rather than "display the
                previous page" key).

      PgDn      Displays the next window-full of file names

      End       Returns to the previous window or DOS.

Hold it ... !  What's that, returns to the previous window?  How did we
get to another.  Ah Ah, you say!  Multiple windows?  Yes indeed ...

To bring up another window, strike shift-F9 again.  A second (third,
fourth) window will spring up on the screen.  You can carry out all the
same manoeuvres here that you did on the preceeding window and then, when
you're done, depress End to return to the "invoking window".

The windows "stack" ... that is, when you invoke a new window and return,
everything will be absolutely as you left it.

(Special note:  when shift-F9 is used as the invoking keystroke, the  \
key carries out the same function for convenience allowing you to bring
up subsequent windows with just 1 keystroke).

Accessing PARTNER from Within Another Program
=============================================
First you must load PARTNER as a permanent part of DOS; you do this using
the following DOS command.  (This command can be included in an AUTOEXEC
batch file so that it is done each time you start your system.)

                   PARTNER/load

Then you can invoke PARTNER from within another program by just depressing
shift + F9.

PARTNER opens a window in the upper left corner of the screen and you
carry on exactly as described before.  When you depress End for the last
time, PARTNER returns to where you invoked it - leaving the screen and
operating environment exactly as you left it.

There are, however, two known exceptions.  PARTNER does not work with:

      o  screens in graphics mode

      o  screens in 40-column text mode

The window position, size and sub-directory settings are remembered so you
won't have to re-specify them the next time you enter PARTNER.

Moving the Windows About
========================
Ctrl + one of the cursor movement keys (Home, End, left-arrow, right-arrow,
PgUp or PgDn) causes the window to move about the screen in the direction
you designate.

(Literary license again:  Ctrl+PgUp and Ctrl+PgDn are used in place of the
more obvious Ctrl+up/down arrow because the keys in the middle, vertical
row of the numeric keypad on this machine (@#$%^) don't register through
the normal BIOS calls).

You can place the windows virtually anywhere on the screen and change their
size using the F1, F3, F5 and F7 keys.  The settings are remembered from one
use to the next.  You can overlap them ... or not ... as you desire.

By default, windows 1-3 don't overlap and windows 1-2 leave the bottom of
the screen un-obstructed.  But, the choice is ultimately yours.

Just the Enter Key
==================
The Enter Key is powerful.  When the "file pointer cursor" is highlighting
a filename, you indicate that you want to examine a new set of files by
just depressing the Enter key.  The top of the window is opened, allowing
you to type a new directory search specification.

You can enter a new drive, sub-directory or filename in conjunction with
any wildcard pattern (ie: ? and *) and that will be used as the target for
the next directory display.

If you have "logged" this window into a particular sub-directory using
the F8-Change Directory key, then you may temporarily override this by
specifying a different drive or sub-directory.  All actions like Removing,
Displaying (ie: typing) and Renaming are now relevant to this directory
and not the one you specified using the F8-Change Directory command.
Of course, the default assigned to the window is used when you don't
specify a "path" in the request line.

That's just like in DOS, where you can CD to a particular sub-directory,
yet operate on files outside that directory by using the appropriate
syntax on a Del command.  Here, the override "sticks" until you depress
the Enter key again to request a new directory display.  The override
most definitely "sticks" while using the PgUp, PgDn and "window
invocation" keys (ie: Shift-F9) ... would you really want it to work any
other way?

If you want to display the contents of a sub-directory, then the directory
request must terminate with a \.  For example:

                   e:\wv\correspondance\

displays the contents of the files in that sub-directory (the trailing *.*
is assumed), whereas

                   e:\wv\correspondance

only tests   e:\wv   for the presence of the sub-directory "correspondance".

If you do not specify a drive or pathname then the search is assumed to
occur in the current, default sub-directory on the default drive.

F2 - Remove a File
==================
Touching F2 removes the file.  Be careful out there!  If you slip you'll
need some assistance from Mr. Norton.

F4 - Copy a File
================
Touching F4 will copy the file.  You are prompted for the name of the
destination -- enter a new filename.  The filename can contain a drive
letter but no sub-directory or pathname.  You can specify a drive letter
alone (leaving the filename blank) and the file will be copied to the
destination drive retaining its name.

Now this copy isn't exactly the same as the DOS copy and there are some
restrictions.

      o  the output filename cannot specify a sub-directory; you
         can only specify an optional drive letter (ie: A:, B: etc)

      o  you can specify a whole new filename or leave the filename
         blank.  You cannot use any form of DOS wildcard construct
         with * and ?.  If the filename is left blank, then of course
         it is copied to the output drive using the same name.

If you want to copy a file from one sub-directory to another on the same
drive then use F6-Rename, instead.

If you want to copy a file from one sub-directory to another on different
drives then use the following procedure.

      o  "Log" this window onto the desired, destination drive
         and sub-directory using the F8-Change Directory function
         You will obtain a list of filenames on that drive.

      o  Now, strike the Enter key to request the display of a new directory.

      o  Enter the name of the directory containing your desired
         source file or the specific source filename.  Press
         Enter to display the contents of that directory and
         then move the cursor on top of the source filename.

      o  Press F4-copy.  Enter the drive letter and, optionally,
         a new name for the file you want to copy.

         Because you have set the default directory on this
         window for the desired destination drive and sub-
         directory the output will be directed there.

If you are only working with drive names (that is, you don't use sub-
directories) then the above isn't necessary since you can use any drive
letter in the destination filname and select any drive letter using the
Enter key request display.

Yes, this is a bit complicated!  A bit you say ... !!!  Well, we'll fix it
when we receive the 3.0 version of Turbo.  In the meantime, think of all
the fun you'll have moving files about from within 1-2-3 (tm) that you
could never access before!

F6 - Rename a File
==================
PARTNER makes it easy.  Touch F6, you will be prompted for a new name.
Type any name you wish, including a sub-directory that may be different
from the one you are displaying.  The file will be renamed and, possibly,
moved from one sub-directory to another in the process.

You must type a full filename.  No wildcard constructs are allowed.

F8 - "Log into a new Sub-Directory"
===================================
Each window refers to a default drive and sub-directory.  When you access
a window for the first time, the directory and drive default to the one
in use in the "invoking window".

This makes it easy for you to set up some defaults to quickly obtain
directories and perform file maintenance work for sub-directories without
having to type-in the whole tree-structured name for most accesses.

You change the default value for a window using the F8-Change Directory
command.  When you press F8, PARTNER prompts you for the name of a new
directory.  You enter a new directory and optional drive designator in
the usual DOS format, eg:

                   d:\sub1\sub2\sub3

Now all directory requests made in this window will, by default, refer
to this "path".  But, you can override this at any time when providing
a new search request after striking the Enter key.

For example, suppose you had entered this in response to the F8-Change
Directory prompt:

                   d:\wv\correspondance

All further requests in this window that do not specify a drive-
letter and path will revert to  d:\wv\correspondance.   But, you
can enter any other drive, path and filename to temporarily
override this when requesting a directory display by striking
the Enter key.

If you think about it, that's exactly the way DOS operates too.  You can
specify a default path and drive and yet always override it on DIR requests.

Getting a bit technical, remember that if you specify

                   d:

and not

                   d:\

the d: request indicates the sub-directory now in default effect and not
the root directory on the volume.

Of course, if all this is complicated and you really don't use a lot of
sub-directories you can ignore all of this and just stick to using drive
letters.  Remember that a window can have a particular drive letter as
its default if you just respond with d: to the F8-Change Directory prompt.

The default directory and drive are always shown on the 25th line of the
display.  You are referring to this when you do not specify an override.

F10 - More Information
======================
F10 - More displays detailed information about the file's size,
timestamp and attributes.

F9 - Display (Type) the File
============================
A handy feature ... a quick touch of the F9 key will open a window and
display the ASCII contents on the screen.  If you use this on non-text
files it could send your display awry.



PARTNER - Some Technical Notes
==============================
PARTNER was written to demonstrate how to use Turbo Pascal's interrupt,
BIOS and MS-DOS access facilities.  Principally,

      o  PARTNER attaches the keyboard interrupt, when permanently
         loaded as part of DOS, and watches for the shift-F9 keystroke.

      o  It saves the registers and manipulates the stack so
         that the CPU can run in "Turbo space".

      o  It carefully ensures that the external environment
         including the registers, screen and Disk Transfer Area
         (DTA) are left un-altered when control is finally
         returned to the interrupted program.  Of course, files
         may have been removed, re-named or copied.

      o  PARTNER sometimes terminates if you get a device timeout on
         a non-ready disk drive.  This can occur if you do a directory
         on a drive letter that is defined but not ready (eg:
         non-existant RamDisk).  If you reply "I" to ignore the
         error several times you may clear it.  Responding "A" to abort
         will return you to the DOS command prompt terminating your
         application too!   We don't like it either but we thought
         we'd be honest and warn you.  We'd welcome any thoughts on
         how to easily improve this.

PARTNER intercepts the keyboard interrupt vector (vector[$09]).  However,
it must "call" the BIOS keyboard handler each time a keystroke occurs
so that the BIOS can decode the input ScanCodes and place the character
into the DOS keyboard buffer.  To perform the "call", the original contents
of vector[$09] are stored in vector[111] and accessed via an Int 111
instruction.  If the use of vector[111] conflicts with some hardware or
other software you have installed, you can obtain the program source and
change this to some other un-used location.

PARTNER could have a lot of extra bells and whistles.  In fact you might
want to obtain the program's Turbo (tm) source code and try adding them
yourself.  We kept it as small as we could since we wanted to run it most
of the time yet not have PARTNER be the dominant application in the machine.

PARTNER requires some 52k of memory by default.  Actually, the maximum it
can use for the time being is 64k since that is the limit imposed by the
DOS $27 lock-program-in-core interrupt service.  Each window invocation
requires about 5k (equivalent to $138, 16-byte paragraphs in 8088
terminology).  Therefore, memory use can be summarized as follows:

      Turbo runtime routines        11k
      PARTNER program code          16k
      Stack / Heap space            25k
                                   -----
      Total                         52k  approx

You can reduce this by re-compiling the program using Borland's
version 2.0 Pascal compiler and specifying a smaller Stack /
Heap space.  That is, use the following series of keystrokes to
set the Options:

           Key Stroke         Means

              O           options
              C           COM file
              I0          Stack is minimum of 0 bytes
              A620        Stack is maximum of 25k bytes
              Q           Quit options
              C           Compile to floppy

By specifying the A option as a smaller multiple of $138, you can generate
a system capable of displaying at most 1, 2 or 3 windows.  Remember that
the F10-More and F9-Display commands require a full 5k stack-frame
to operate within as well.

Techniques you might try to reduce memory, at the expense of execution
speed, (if you're adventurous) would be to:

      o  write the screen images to a diskfile rather than hold
         them within the program stack (at a saving of 5000 bytes per panel)

      o  turn some of the procedures into overlays allowing you
         to write gallons more code at negligible memory cost

Both of these techniques would require you to ensure that the original
disk was always available (ie: not a floppy) so that it would not
overwrite data or load improperly.

For those interested in studying the interrupt invocation code: you will
notice that Borland's Turbo manual leaves a bit to be desired in terms
of completeness in this area.  In short, the instructions in Borland's
manual flatly don't work!  Much more code is needed and the Inline
statements incorporated within PARTNER provide a proper, "cookbook"
solution.  See the March-June '85 issues of Tug Lines for a description
or contact the author.

Incompatibilities
=================
PARTNER was written as an educational exercise ... and that it was.
We found lots of areas where additional sophisticated programming would
be required to make it work perfectly in all cases.

PARTNER works by replacing the DOS keyboard interrupt vector with the
address of its own code.  Early during execution of the interrupt
procedure, PARTNER calls the "original vector" to ensure that whatever
was supposed to happen before happens too.  That's why keyboard I/O
works at all with PARTNER running.  In this way, PARTNER acts as an
interceder ... getting into the middle of the action but not taking
part unless it specifically sees the shift-F9 sequence.

Consequently, it is comptatable with lots of programs.  However, we
know of the following problems:

1.    Bruce and James' WordVision and SmartTerm 100 also choose
      to execute when a keyboard interrupt occurs ... but they,
      unlike PARTNER, don't act as interceders - they take the
      interrupt for keeps and do not pass control to other
      programs that may have intercepted the interrupt vector.
      Consequently PARTNER never gets a chance to see the
      interrupt and is locked out until the programs terminate
      and restore the vector's contents.

      You can use PARTNER with these programs but it won't be
      accessible again until you terminate them.

2.    Prokey(tm) (from RoseSoft) is a little more consistent in
      that it too acts as an interceder.  The two work together
      ... for a while.  Finally one or the other seems to mix up
      the "true" contents of the keyboard's interrupt vector,
      causing a loop and a re-boot is required.

      Don't use PARTNER in conjunction with ProKey.

3.    SideKick from Borland is a truly interesting case.
      Sidekick handles the problem posed in case 1 since it
      periodically examines the contents of the keyboard vector
      (presumably from within the timer interrupt) and forcibly
      restores its own address over anything else that was there
      (in vector[$09]) if some other program has possessed the
      audaucity to change it !  Sidekick, having thus ensured it
      will always control the keyboard, kindly passes control
      down the keyboard interrupt chain if it doesn't want to
      react to the keys pressed.  Great, SideKick works from
      within WordVision !  However the bad news is that the
      wholesale confusion over exactly who own the hardware
      vector address, what its contents really should be when
      various programs terminate and what to restore it to at
      any given time when returning from the interrupt handler
      causes the machine to lock up in a series of mysterious
      ways after operating for a while.

      Don't use PARTNER in conjunction with SideKick and
      especially don't use it in conjuction with SideKick +
      WordVision + ProKey.

4.    PARTNER seems to work fine with DOSEDIT ... that little guy
      obeys the rules.  (DOSEDIT is a bulletin board program that
      provides enhanced editing capabilities on the DOS command
      prompt line).

      You can use PARTNER with DOSEDIT.

5.    No problems from within:

                   BASIC     watch out for 40-column screens

                   1-2-3     watch out for the graphics screen

                   Turbo     that's why we wrote it because Turbo,
                             excellent environment that it is, can't do
                             this stuff when you really, really need it.